graphql-docs-and-tests — Top-level Summary

Branch focused on hardening Raphtory's GraphQL surface: documenting it, expanding what its inputs accept, and verifying it from Python. Also picks up housekeeping on the Python bindings (PyO3 stubs, PyProp constructors).

Fixes #1937 #2101 #2238 #2302 #2301 #2300

Need to get smmoosavi/dynamic-graphql#42 merged

1. GraphQL schema: documentation + tests

• Every resolver type, field, and argument now carries a doc comment intended for the public docs site.
• Permission requirements on every root-query / mutation now follow a consistent format (Requires READ on the graph., Requires WRITE on the parent namespace., etc.).
• Filled in coverage for previously untested resolvers; added Python integration tests around them.
• Picked up a forked dynamic-graphql branch that exposes per-argument desc attributes (the released crate has no such hook).

2. New / widened input scalars

Made a new NodeId for String or non-negative Int similar to TimeInput. The two scalars are wired through every relevant resolver: lookups (node, edge, hasNode, hasEdge), view transforms (subgraph, excludeNodes, sharedNeighbours), all mutations (addNode, addEdge, deleteEdge, batch variants, MutableGraph.{node,edge}), createSubgraph, and VectorSelection.{addNodes,addEdges}.

Node.id and Edge.id now return NodeId (so an integer-indexed graph returns integers, not stringified ones).

Filters already accepted both forms via the existing Value scalar — no schema change there, just verified.

3. Graph-semantics override

graph(path: ..., graphType: EVENT | PERSISTENT) (and the same arg on MutableGraph.graph) lets a caller re-interpret a stored graph at query time:

• An event graph queried with graphType: PERSISTENT carries values forward in windows after the addition.
• A persistent graph queried with graphType: EVENT only sees updates exactly at the queried time.

4. Temporal-property API changes

• TemporalProperty.values now returns typed PropValues instead of stringified values.
• Added Python-style aggregates on TemporalProperty: sum, mean, median, min, max, count, average. Returning null for non-numeric value types.
• unique and orderedDedupe return a TemporalProperty so the aggregates compose.

5. Python tests added

6. Python bindings (raphtory-api, raphtory)

New Prop / PropType constructors

• Prop.aware_datetime(dt) — tz-aware datetime (UTC-stored). Naive input rejected.
• Prop.naive_datetime(dt) — tz-naive datetime.
• Prop.decimal(value) — accepts decimal.Decimal, str, int, or float.
• PropType.decimal(scale) — schema-side companion (PropType.datetime() / PropType.naive_datetime() already existed). Lets load_nodes/load_edges accept schema={"col": PropType.decimal(2)} to cast string or Arrow Decimal128 columns.

Stub generation (gen-stubs.py)

• Audited every PyO3 method for missing docs / return types / parameter docs.
• Registered iterable wrapper classes (PyPropValueListList, PyTemporalPropsList, PyTemporalPropsListList, PyPropHistValueList, PyPropHistValueListList, PyTemporalPropList, PyTemporalPropListList, PyPropHistItemsList, PyPropHistItemsListList, PropIterable) plus EmbeddingServer, RunningEmbeddingServer, OutputNodeState so they resolve in generated stubs.
• Aliased raphtory.iterables and raphtory.gql into sys.modules so submodule imports resolve.
• Renamed Rust types in docstrings to match exported Python names (PyOutputNodeState → OutputNodeState, TypedNodeState → OutputNodeState, Str → str, NumpyArray → NDArray, etc.).
• Result: gen-stubs.py reports zero warnings; mypy -m raphtory passes. (other than GQL which we can fix later)

7. dynamic-graphql fork

Submitted upstream PR adding desc attribute support on ResolvedObjectFieldsArg / InterfaceMethodArg / ExpandObjectFieldsArg. Branch add-arg-descriptions of miratepuffin/dynamic-graphql is referenced from this repo's Cargo.toml until upstream merges.